<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>IniRead</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>IniRead</h1>

<p>Reads a value, section or list of section names from a standard format .ini file.</p>

<pre class="Syntax">IniRead, OutputVar, Filename, Section, Key [, Default]
IniRead, OutputVarSection, Filename, Section
IniRead, OutputVarSectionNames, Filename
</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd>
      <p>The name of the variable in which to store the retrieved value. If the value cannot be retrieved, the variable is set to the value indicated by the <em>Default</em> parameter (described below).</p>
    </dd>
  
  <dt>OutputVarSection</dt>
  <dd><p><span class="ver">[AHK_L 57+]:</span> Omit the <em>Key</em> parameter to read an entire section. Comments and empty lines are omitted. Only the first 65,533 characters of the section are retrieved.</p></dd>
  
  <dt>OutputVarSectionNames</dt>
  <dd><p><span class="ver">[AHK_L 57+]:</span> Omit the <em>Key</em> and <em>Section</em> parameters to retrieve a linefeed (<code>`n</code>) delimited list of section names.</p></dd>

  <dt>Filename</dt>
  <dd><p>The name of the .ini file, which is assumed to be in <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> if an absolute path isn't specified.</p></dd>

  <dt>Section</dt>
  <dd><p>The section name in the .ini file, which is the heading phrase that appears in square brackets (do not include the brackets in this parameter).</p></dd>

  <dt>Key</dt>
  <dd><p>The key name in the .ini file.</p></dd>

  <dt>Default</dt>
  <dd><p>The value to store in <em>OutputVar</em> if the requested key is not found. If omitted, it defaults to the word ERROR. To store a blank value (empty string), specify <a href="../Variables.htm#Space">%A_Space%</a>.</p>
      <p><span class="ver">[AHK_L 57+]:</span> This parameter is not used if <i>Key</i> is omitted.</p>
      </dd>

</dl>
<h3>ErrorLevel</h3>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is <strong>not</strong> set by this command. If there was a problem, <em>OutputVar</em> will be set to the <em>Default</em> value as described above.</p>
<h3>Remarks</h3>
<p>The operating system automatically omits leading and trailing spaces/tabs from the retrieved string. To prevent this, enclose the string in single or double quote marks. The outermost set of single or double quote marks is also omitted, but any spaces inside the quote marks are preserved.</p>
<p>Values longer than 65,535 characters are likely to yield inconsistent results.</p>
<p>A standard ini file looks like:</p>
<pre>[SectionName]
Key=Value</pre>
<p><b>Unicode:</b> IniRead and IniWrite rely on the external functions <a href="http://msdn.microsoft.com/en-us/library/ms724353.aspx">GetPrivateProfileString</a> and <a href="http://msdn.microsoft.com/en-us/library/ms725501.aspx">WritePrivateProfileString</a> to read and write values. These functions support Unicode only in UTF-16 files; all other files are assumed to use the system's default ANSI code page.</p>
<h3>Related</h3>
<p><a href="IniDelete.htm">IniDelete</a>, <a href="IniWrite.htm">IniWrite</a>, <a href="RegRead.htm">RegRead</a>, <a href="LoopReadFile.htm">file-reading loop</a>, <a href="FileRead.htm">FileRead</a></p>
<h3>Example</h3>
<pre class="NoIndent">IniRead, OutputVar, C:\Temp\myfile.ini, section2, key
MsgBox, The value is %OutputVar%.</pre>

</body>
</html>
